home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / PInterfaces / BlockStoragePlugin.p < prev    next >
Encoding:
Text File  |  1996-05-01  |  42.4 KB  |  1,181 lines  |  [TEXT/MPS ]
  1. {
  2.      File:        BlockStoragePlugin.p
  3.  
  4.      Contains:    Block Storage Plug In Programming Interface
  5.  
  6.      Version:    Technology:    Copland
  7.                  Release:    Universal Interfaces 3.0d3 on Copland DR1
  8.  
  9.      Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10.  
  11.      Bugs?:        If you find a problem with this file, send the file and version
  12.                  information (from above) and the problem description to:
  13.  
  14.                      Internet:    apple.bugs@applelink.apple.com
  15.                      AppleLink:    APPLE.BUGS
  16.  
  17. }
  18. {$IFC UNDEFINED UsingIncludes}
  19. {$SETC UsingIncludes := 0}
  20. {$ENDC}
  21.  
  22. {$IFC NOT UsingIncludes}
  23.  UNIT BlockStoragePlugin;
  24.  INTERFACE
  25. {$ENDC}
  26.  
  27. {$IFC UNDEFINED __BLOCKSTORAGEPLUGIN__}
  28. {$SETC __BLOCKSTORAGEPLUGIN__ := 1}
  29.  
  30. {$I+}
  31. {$SETC BlockStoragePluginIncludes := UsingIncludes}
  32. {$SETC UsingIncludes := 1}
  33.  
  34. {$IFC UNDEFINED __TYPES__}
  35. {$I Types.p}
  36. {$ENDC}
  37. {$IFC UNDEFINED __ERRORS__}
  38. {$I Errors.p}
  39. {$ENDC}
  40. {$IFC UNDEFINED __FILEMANAGERTYPES__}
  41. {$I FileManagerTypes.p}
  42. {$ENDC}
  43. {$IFC UNDEFINED __NAMEREGISTRY__}
  44. {$I NameRegistry.p}
  45. {$ENDC}
  46. {$IFC UNDEFINED __BLOCKSTORAGE__}
  47. {$I BlockStorage.p}
  48. {$ENDC}
  49. {$IFC UNDEFINED __IOMEMORYLISTS__}
  50. {$I IOMemoryLists.p}
  51. {$ENDC}
  52.  
  53. {$PUSH}
  54. {$ALIGN POWER}
  55. {$LibExport+}
  56.  
  57. {$IFC FOR_SYSTEM8_PREEMPTIVE }
  58. {
  59. ******************************************************************************
  60.  *******************************************************************************
  61.  *******************************************************************************
  62.  
  63.     Plug In Constants
  64.     
  65.  *******************************************************************************
  66.  *******************************************************************************
  67.  *****************************************************************************
  68. }
  69. {
  70. ******************************************************************************
  71.     
  72.     Options to a BSIOFunc
  73.     
  74.  *****************************************************************************
  75. }
  76.  
  77. CONST
  78.     kBSRead                        = 0;
  79.     kBSWrite                    = 1;
  80.  
  81. {
  82. ******************************************************************************
  83.  
  84.     Mapping Plug-In Level of Confidence values
  85.     
  86.  *****************************************************************************
  87. }
  88.     kBSMPIDeviceNotSupported    = 0;
  89.     kBSMPIDeviceTypeRecognized    = 1;
  90.     kBSMPIDeviceMfrRecognized    = 2;
  91.     kBSMPIDeviceModelRecognized    = 3;
  92.     kBSMPIDeviceMediaRecognized    = 4;
  93.  
  94.  
  95. TYPE
  96.     BSMPIConfidenceLevel                = UInt32;
  97. {
  98. ******************************************************************************
  99.  
  100.     Mapping Plug-In Level of Confidence values
  101.     
  102.  *****************************************************************************
  103. }
  104.  
  105. CONST
  106.     kBSCPIDeviceNotSupported    = 0;
  107.     kBSCPIDeviceTypeRecognized    = 1;
  108.     kBSCPIDeviceMfrRecognized    = 2;
  109.     kBSCPIDeviceModelRecognized    = 3;
  110.  
  111.  
  112. TYPE
  113.     BSCPIConfidenceLevel                = UInt32;
  114. {
  115. ******************************************************************************
  116.  
  117.     Plug In Version - this tracks the revision of the plug-in interface and
  118.         should be placed in the version field of the plug-in interface structure
  119.     
  120.  *****************************************************************************
  121. }
  122.  
  123. CONST
  124.     kBSPlugInInterfaceVersion    = $02011996;
  125.  
  126. {
  127. ******************************************************************************
  128.  
  129.     BSIOStatus values
  130.     
  131.  *****************************************************************************
  132. }
  133.     kBSIOCompleted                = 1;
  134.     kBSIOContinuing                = 2;
  135.     kBSIOFailed                    = 3;
  136.     kBSIONotStarted                = 4;
  137.  
  138.  
  139. TYPE
  140.     BSIOStatus                            = UInt32;
  141. {
  142. ******************************************************************************
  143.  *******************************************************************************
  144.  *******************************************************************************
  145.  
  146.     Types
  147.     
  148.  *******************************************************************************
  149.  *******************************************************************************
  150.  *****************************************************************************
  151. }
  152.     BSStorePtr                            = Ptr;
  153.     BSContainerPtr                        = Ptr;
  154.     BSIORequestBlockPtr                    = Ptr;
  155.     BSIOErrors                            = OSStatus;
  156. {
  157. ******************************************************************************
  158.     BSErrorList:  another structure to manage I/O success/failure.
  159.  
  160.     BSErrorList data structure allows a Mapping Plug-In to keep track of the
  161.     current state of each transfer request sent to it by the Block Storage client.  If transfers complete
  162.     successfully, a pointer 0 is returned.  If an error occurs, a linked list (?) of these data structures
  163.     is returned specifying the exact state of each transfer request.
  164.  
  165.     startingBlock:        The initial transfer block of this fragment of the request
  166.     blockCount:            The number of blocks to be transfered including the startingBlock
  167.     status:                A constant representing the final state of the transfer of the blocks:
  168.                                  kIONotStarted:                No processing was begun on these blocks
  169.                                 kIOStarted:                    The BS Plug-In began to process the blocks
  170.                                 kIOToFamily:                The request was sent to the device family
  171.                                 kIOComplete:                The request completed normally
  172.                                  kIOFailed:                    The request failed to complete execution
  173.     error:                The exact error, if any
  174.     xferID:                An index representing which request of a multiple-request I/O this is
  175.      next:                A pointer to the next data structure (could be eliminated in favor of indices)
  176.  *****************************************************************************
  177. }
  178.     BSErrorListPtr = ^BSErrorList;
  179.     BSErrorList = RECORD
  180.         startingBlock:            BSByteCount;
  181.         length:                    BSByteCount;
  182.         status:                    UInt32;
  183.         error:                    BSIOErrors;
  184.         xferID:                    ItemCount;
  185.         next:                    BSErrorListPtr;
  186.     END;
  187.  
  188. {
  189. ****************************************************************************
  190.  
  191.     BSStoreMPIComponent describes a component of a Store.  A component may
  192.     be an external device or another Store.  This is the internal form of
  193.     BSStoreComponent.
  194.     
  195.  ***************************************************************************
  196. }
  197.     BSStoreMPIComponentPtr = ^BSStoreMPIComponent;
  198.     BSStoreMPIComponent = RECORD
  199.         componentType:            BSComponentType;
  200.         startingOffset:            BSByteCount;                            {  Where in the Store this  }
  201.                                                                         {  component will be placed  }
  202.         sourceNode:                RegEntryRef;                            {  Physical components  }
  203.         srcStore:                BSStorePtr;                                {  Logical components  }
  204.         partitionInfo:            BSPartitionDescriptor;                    {  Logical components  }
  205.     END;
  206.  
  207. {
  208. ******************************************************************************
  209.  
  210.     BSStoreMPIInfo - Information about the Store that the Mapping Plug-in can
  211.         provide
  212.         
  213.  *****************************************************************************
  214. }
  215.     BSStoreMPIInfoPtr = ^BSStoreMPIInfo;
  216.     BSStoreMPIInfo = RECORD
  217.         curState:                BSAccessibilityState;
  218.         storeSize:                BSByteCount;
  219.         readBlockSize:            BSByteCount;                            {  minimum read size & granularity  }
  220.         writeBlockSize:            BSByteCount;                            {  minimum write size & granularity  }
  221.         isEjectable:            BOOLEAN;
  222.         isWriteable:            BOOLEAN;
  223.         hasAutoEjectHardware:    BOOLEAN;
  224.         isFormattable:            BOOLEAN;
  225.         isPartitionable:        BOOLEAN;
  226.         isFilesystem:            BOOLEAN;
  227.         reserved1:                BOOLEAN;
  228.         reserved2:                BOOLEAN;
  229.         curFormat:                BSStoreFormatInfo;
  230.         possibleFormats:        ARRAY [0..7] OF BSStoreFormatInfo;
  231.         name:                    PACKED ARRAY [0..47] OF CHAR;
  232.     END;
  233.  
  234. {
  235. ******************************************************************************
  236.  
  237.     BSStorePPIInfo - Information about the Store that the Partitioning Plug-in 
  238.         can provide
  239.         
  240.  *****************************************************************************
  241. }
  242.     BSStorePPIInfoPtr = ^BSStorePPIInfo;
  243.     BSStorePPIInfo = RECORD
  244.         numPartitions:            ItemCount;
  245.         maxPartitions:            ItemCount;
  246.     END;
  247.  
  248. {
  249. ******************************************************************************
  250.  
  251.     BSContainerPIInfo - Information about the Container that the Container
  252.         Plug-in can provide
  253.         
  254.  *****************************************************************************
  255. }
  256.     BSContainerPIInfoPtr = ^BSContainerPIInfo;
  257.     BSContainerPIInfo = RECORD
  258.         numChildren:            ItemCount;
  259.         isEjectable:            BOOLEAN;
  260.     END;
  261.  
  262. {
  263. ******************************************************************************
  264.  *******************************************************************************
  265.  *******************************************************************************
  266.  
  267.     Plug-In Interface Functions
  268.     
  269.  *******************************************************************************
  270.  *******************************************************************************
  271.  *****************************************************************************
  272. }
  273. {
  274. ******************************************************************************
  275.  *******************************************************************************
  276.  
  277.     Mapping Plug-In Interface
  278.     
  279.  *******************************************************************************
  280.  *****************************************************************************
  281. }
  282. {
  283. ******************************************************************************
  284.     BSMappingPIExamine - Plug-in's opportunity to examine a device and determine
  285.             if it is an appropriate plug-in for it
  286.     
  287.     Inputs:        examineStore - a pointer to the in-process Store to be examined
  288.     
  289.     Outputs:    confidence - level of confidence the plug-in has that the plugin
  290.                 is the correct one
  291.     
  292.     Returns:    E_BSSuccess if no errors happened examining the device.  
  293.                 If an error happened, the error received from the other family is
  294.                 returned
  295.  *****************************************************************************
  296. }
  297.     BSMappingPIExamine = ProcPtr;  { FUNCTION BSMappingPIExamine(examineStore: BSStorePtr; VAR confidence: BSMPIConfidenceLevel): OSStatus; C; }
  298.  
  299. {
  300. ******************************************************************************
  301.  
  302.     BSMappingPIInit - Plug-in's initialization routine.  Called when plug-in
  303.             is selected for a Store.  Plug-in's opportunity to initialize
  304.             device, allocate data structures, etc.
  305.     
  306.     Inputs:        initStore - a pointer to the Store this plug-in will be attached
  307.                     to
  308.     Outputs:    curState - the current state of the media
  309.     
  310.     Returns:    E_BSSuccess if successful
  311.     
  312.  *****************************************************************************
  313. }
  314.     BSMappingPIInit = ProcPtr;  { FUNCTION BSMappingPIInit(initStore: BSStorePtr): OSStatus; C; }
  315.  
  316. {
  317. ******************************************************************************
  318.  
  319.     BSMappingPICleanup - Plug-in's dispose routine.  Called when Store is
  320.             being disposed of.  Should dispose of any memory or data structures
  321.             held for this Store, finalize all I/O for Store
  322.     
  323.     Inputs:        cleanupStore - Store that is being disposed of
  324.     
  325.     Outputs:    <none>
  326.     
  327.     Returns:    E_BSSuccess if successful
  328.     
  329.  *****************************************************************************
  330. }
  331.     BSMappingPICleanup = ProcPtr;  { FUNCTION BSMappingPICleanup(cleanupStore: BSStorePtr): OSStatus; C; }
  332.  
  333. {
  334. ******************************************************************************
  335.     BSMappingPIIO - Plug-in's input/output routine
  336.     
  337.     Inputs:        ioStore - the Store on which IO is to be performed
  338.                 blocks - descriptor of the blocks to do IO on
  339.                 memory - descriptor of the memory to do IO on (memory has been prepared)
  340.                 parentRequest - the request this request is being made on behalf of
  341.                 options - read/write
  342.     
  343.     Outputs:    errors - where exactly the errors occured, if any
  344.     
  345.     Returns:    kBSIOContinuing if IO was started successfully and the I/O
  346.                     completion routine still needs to be called
  347.                 kBSIOCompleted if IO was completed and no further action is
  348.                     necessary
  349.                 kBSIOFailed if IO failed for some reason
  350.                 kBSIONotStarted if the IO could not be started
  351.  *****************************************************************************
  352. }
  353.     BSMappingPIIO = ProcPtr;  { FUNCTION BSMappingPIIO(ioStore: BSStorePtr; blocks: BSBlockListDescriptorRef; memory: MemListDescriptorRef; parentRequest: BSIORequestBlockPtr; options: OptionBits; VAR errors: BSErrorListPtr): BSIOStatus; C; }
  354.  
  355. {
  356. ******************************************************************************
  357.     BSMappingPIFlush - flush plug-in's cached data (if any)
  358.             BSMappingPIFlush flushes the plug-in's cached data.  It is called
  359.             in a similar fashion to an I/O request.  BSStoreRW may be used
  360.             as may BSStoreFlush.
  361.     
  362.     Inputs:        flushStore - the Store on which flush is to be performed
  363.                 parentRequest - the request this request is being made on behalf of
  364.     
  365.     Outputs:    errors - where exactly the errors occured, if any
  366.     
  367.     Returns:    kBSIOContinuing if IO was started successfully and the I/O
  368.                     completion routine still needs to be called
  369.                 kBSIOCompleted if IO was completed and no further action is
  370.                     necessary
  371.                 kBSIOFailed if IO failed for some reason
  372.                 kBSIONotStarted if the IO could not be started
  373.  *****************************************************************************
  374. }
  375.     BSMappingPIFlush = ProcPtr;  { FUNCTION BSMappingPIFlush(ioStore: BSStorePtr; parentRequest: BSIORequestBlockPtr; VAR errors: BSErrorListPtr): BSIOStatus; C; }
  376.  
  377. {
  378. ******************************************************************************
  379.     BSMappingPIAddComponent - Notifies Plug-in about new components to be added
  380.         to it
  381.     
  382.     Inputs:        destStore - the Store the blocks are to be mapped into
  383.                 newComponent - the new Component to be mapped in
  384.     
  385.     Outputs:    storeNewInfo - the new information about the Store
  386.  
  387.     
  388.     Returns:    E_BSSuccess if successful
  389.                 E_BSMPITooManyMappings if no more mappings can be handled
  390.                 E_BSMPIOutOfStoreBounds if the start of the destination blocks 
  391.                     would cause a gap in the Store
  392.     
  393.  *****************************************************************************
  394. }
  395.     BSMappingPIAddComponent = ProcPtr;  { FUNCTION BSMappingPIAddComponent(destStore: BSStorePtr; VAR newComponent: BSStoreMPIComponent; VAR storeNewInfo: BSStoreInfo): OSStatus; C; }
  396.  
  397. {
  398. ******************************************************************************
  399.     BSMappingPIGoToState - Requests plug-in to take Store to the specified 
  400.             accessibility state.  
  401.     
  402.     Inputs:        theStore - Store to take to the state
  403.                 gotoState - what state to go to (possible states defined above)
  404.                                 
  405.     
  406.     Outputs:    <none>
  407.  
  408.     Returns:    E_BSSuccess if successful
  409.     
  410.  *****************************************************************************
  411. }
  412.     BSMappingPIGoToState = ProcPtr;  { FUNCTION BSMappingPIGoToState(theStore: BSStorePtr; gotoState: BSAccessibilityState): OSStatus; C; }
  413.  
  414. {
  415. ******************************************************************************
  416.     BSMappingPIFormatMedia - tells plug-in to do a low-level format of the media
  417.     
  418.     Inputs:        formatStore - Store to format
  419.     
  420.     Outputs:    <none>
  421.     
  422.     Returns:    E_BSSuccessful if successful
  423.     
  424.  *****************************************************************************
  425. }
  426.     BSMappingPIFormatMedia = ProcPtr;  { FUNCTION BSMappingPIFormatMedia(formatStore: BSStorePtr; formatType: BSFormatIndex): OSStatus; C; }
  427.  
  428. {
  429. ******************************************************************************
  430.     BSMappingPIGetInfo - gets information about the device and the plug-in
  431.     
  432.     Inputs:        formatStore - Store to format
  433.     
  434.     Outputs:    info - the filled in information
  435.     
  436.     Returns:    E_BSSuccessful if successful
  437.     
  438.  *****************************************************************************
  439. }
  440.     BSMappingPIGetInfo = ProcPtr;  { FUNCTION BSMappingPIGetInfo(infoStore: BSStorePtr; VAR info: BSStoreMPIInfo): OSStatus; C; }
  441.  
  442. {
  443. ******************************************************************************
  444.     BSMappingIOCompletion - I/O completion routine for a mapping plug-in
  445.     
  446.     Inputs:        theStore:  - A pointer to the Store in question
  447.                 finishedPrivateData - A pointer to the private data the Mapping 
  448.                     plug-in associated with this I/O
  449.                 returnedBSErrorList - A pointer to a BSErrorList if the 
  450.                     triggering event came from another BS plug-in
  451.                 returnedStatus - The OSStatus returned by the other family or 
  452.                     plug-in that was called
  453.     Outputs:    errorListPtrPtr - A pointer to a pointer to a BSErrorList.  
  454.                     The BSErrorList is allocated and filled in by the completion 
  455.                     routine if the I/O has failed.  It should be allocated using 
  456.                     BSErrorListAllocate and will be deallocated by the family code.
  457.     
  458.     Returns:    E_BSSuccess if successful
  459.  
  460.  *****************************************************************************
  461. }
  462.     BSMappingIOCompletion = ProcPtr;  { FUNCTION BSMappingIOCompletion(theStore: BSStorePtr; finishedPrivateData: UNIV Ptr; returnedBSErrorList: BSErrorListPtr; returnedStatus: OSStatus; VAR errorListPtrPtr: BSErrorListPtr): OSStatus; C; }
  463.  
  464.     BlockStoragePlugInInfoPtr = ^BlockStoragePlugInInfo;
  465.     BlockStoragePlugInInfo = RECORD
  466.         version:                UInt32;
  467.         reserved1:                UInt32;
  468.         reserved2:                UInt32;
  469.         reserved3:                UInt32;
  470.     END;
  471.  
  472.     BSStoreMappingOpsPtr = ^BSStoreMappingOps;
  473.     BSStoreMappingOps = RECORD
  474.         header:                    BlockStoragePlugInInfo;
  475.         DeviceExamine:            BSMappingPIExamine;
  476.         Init:                    BSMappingPIInit;
  477.         Cleanup:                BSMappingPICleanup;
  478.         IO:                        BSMappingPIIO;
  479.         Flush:                    BSMappingPIFlush;
  480.         AddComponent:            BSMappingPIAddComponent;
  481.         GotoState:                BSMappingPIGoToState;
  482.         Format:                    BSMappingPIFormatMedia;
  483.         GetInfo:                BSMappingPIGetInfo;
  484.         ioCompletion:            BSMappingIOCompletion;
  485.     END;
  486.  
  487. {
  488. ******************************************************************************
  489.  
  490.     BSMPIBackgroundTask - a background task entry point for a Mapping plug-in.
  491.             BSMPIStartBackgroundTask may be used by the Mapping plug-in to
  492.             start one of these.  The task will be automatically terminated
  493.             after the Cleanup routine is executed
  494.     
  495.     Inputs:        theStore - the Store this is running for
  496.                 theArg - the argument passed to BSMPIStartBackgroundTask
  497.                 
  498.     Outputs:    <none>
  499.     
  500.     Returns:    Errors are ignored but will be logged.
  501.  *****************************************************************************
  502. }
  503.     BSMPIBackgroundTask = ProcPtr;  { FUNCTION BSMPIBackgroundTask(theStore: BSStorePtr; theArg: UNIV Ptr): OSStatus; C; }
  504.  
  505. {
  506. ******************************************************************************
  507.  *******************************************************************************
  508.  
  509.     Partitioning Plug-In Interface
  510.     
  511.  *******************************************************************************
  512.  *****************************************************************************
  513. }
  514. {
  515. ******************************************************************************
  516.     BSPartitioningPIExamine - Plug-in's opportunity to examine a Store and
  517.             determine if it's the right plug-in for it
  518.     
  519.     Inputs:        readStoreConn - a connection to the Store to be examined
  520.     
  521.     Outputs:    certainty - 0 if the plug-in did not recognize the partition
  522.                     map format
  523.                 otherwise the number of bytes read
  524.     
  525.     Returns:    E_BSSuccess if no errors occured
  526.                 E_BSPPIOutOfResources if memory or other resource couldn't
  527.                     be allocated
  528.                 otherwise the Block Storage error from the I/O
  529.     
  530.  *****************************************************************************
  531. }
  532.     BSPartitioningPIExamine = ProcPtr;  { FUNCTION BSPartitioningPIExamine(readStoreConn: BSStoreConnID; VAR certainty: UInt32): OSStatus; C; }
  533.  
  534. {
  535. ******************************************************************************
  536.     BSPartitioningPIInit - Plug-in's initialization routine.  Called when 
  537.             plug-in is selected for a Store.  Plug-in's opportunity to 
  538.             initialize device, allocate data structures, etc.
  539.     
  540.     Inputs:        initStore - pointer to the Store the plug-in is being attached to
  541.                     
  542.     Outputs:    <none>
  543.     
  544.     Returns:    E_BSSuccess if successful
  545.     
  546.  *****************************************************************************
  547. }
  548.     BSPartitioningPIInit = ProcPtr;  { FUNCTION BSPartitioningPIInit(initStore: BSStorePtr): OSStatus; C; }
  549.  
  550. {
  551. ******************************************************************************
  552.  
  553.     BSPartitioningPICleanup - Plug-in's dispose routine.  Called when Store is
  554.             being disposed of.  Should dispose of any memory or data structures
  555.             held for this Store and flush the partition map if necessary
  556.     
  557.     Inputs:        cleanupStore - Store that is being disposed of
  558.     
  559.     Outputs:    <none>
  560.     
  561.     Returns:    E_BSSuccess if successful
  562.     
  563.  *****************************************************************************
  564. }
  565.     BSPartitioningPICleanup = ProcPtr;  { PROCEDURE BSPartitioningPICleanup(cleanupStore: BSStorePtr); C; }
  566.  
  567. {
  568. ******************************************************************************
  569.     BSPartitioningPIInitializeMap - lays down a new partition map on a Store (plug-in has
  570.             already been attached)
  571.     
  572.     Inputs:        initStore - the Store to be initialized
  573.     
  574.     Outputs:    <none>
  575.     
  576.     Returns:    E_BSSuccess if successful
  577.                 otherwise, Block Storage error if I/O fails
  578.     
  579.  *****************************************************************************
  580. }
  581.     BSPartitioningPIInitializeMap = ProcPtr;  { FUNCTION BSPartitioningPIInitializeMap(initStore: BSStorePtr): OSStatus; C; }
  582.  
  583. {
  584. ******************************************************************************
  585.     BSPartitioningPIGetInfo - Gets information about the partition map and the
  586.         partitioning plug-in
  587.     
  588.     Inputs:        store - the Store to read from
  589.     
  590.     Outputs:    info - the filled in information
  591.     
  592.     Returns:    E_BSSuccess if successful
  593.     
  594.  *****************************************************************************
  595. }
  596.     BSPartitioningPIGetInfo = ProcPtr;  { FUNCTION BSPartitioningPIGetInfo(store: BSStorePtr; VAR info: BSStorePPIInfo): OSStatus; C; }
  597.  
  598. {
  599. ******************************************************************************
  600.     BSPartitioningPIGetEntry - Get a particular partition map entry
  601.     
  602.     Inputs:        readStore - the Store
  603.                 entryNum - which entry to read
  604.                 
  605.     Outputs:    retEntry - pointer to a BSPartitionDescriptor that's filled in
  606.                     with the entry
  607.     
  608.     Returns:    E_BSSuccess if successful
  609.                 E_BSPPIPartitionNonExistant if that entry does not exist
  610.                 other Block Storage error if I/O problem
  611.     
  612.  *****************************************************************************
  613. }
  614.     BSPartitioningPIGetEntry = ProcPtr;  { FUNCTION BSPartitioningPIGetEntry(readStore: BSStorePtr; entryNum: ItemCount; VAR retEntry: BSPartitionDescriptor): OSStatus; C; }
  615.  
  616. {
  617. ******************************************************************************
  618.     BSPartitioningSetEntry - Sets the information in a particular partition map
  619.             entry
  620.     
  621.     Inputs:        
  622.     
  623.     Outputs:    
  624.     
  625.     Returns:    
  626.     
  627.  *****************************************************************************
  628. }
  629.     BSPartitioningPISetEntry = ProcPtr;  { FUNCTION BSPartitioningPISetEntry(store: BSStorePtr; partitionNum: ItemCount; VAR partitionInfo: BSPartitionDescriptor): OSStatus; C; }
  630.  
  631.     BSStorePartitioningOpsPtr = ^BSStorePartitioningOps;
  632.     BSStorePartitioningOps = RECORD
  633.         header:                    BlockStoragePlugInInfo;
  634.         Examine:                BSPartitioningPIExamine;
  635.         Init:                    BSPartitioningPIInit;
  636.         Cleanup:                BSPartitioningPICleanup;
  637.         InitializeMap:            BSPartitioningPIInitializeMap;
  638.         GetInfo:                BSPartitioningPIGetInfo;
  639.         GetEntry:                BSPartitioningPIGetEntry;
  640.         SetEntry:                BSPartitioningPISetEntry;
  641.     END;
  642.  
  643. {
  644. ******************************************************************************
  645.  *******************************************************************************
  646.  
  647.     Container Plug-In Interface
  648.     
  649.  *******************************************************************************
  650.  *****************************************************************************
  651. }
  652. {
  653. ******************************************************************************
  654.  
  655.     BSContainerPIExamine - Called to allow the Container plug-in to verify
  656.         that it is correct for the Container
  657.  
  658.     Inputs:        initContainer - the Container in question    
  659.  
  660.     Outputs:    levelOfConfidence - how confident the plug-in is that it is the
  661.                     correct one
  662.  
  663.     Returns:    E_BSSuccess if successful
  664.  
  665.  *****************************************************************************
  666. }
  667.     BSContainerPIExamine = ProcPtr;  { FUNCTION BSContainerPIExamine(initContainer: BSContainerPtr; VAR levelOfConfidence: BSCPIConfidenceLevel): OSStatus; C; }
  668.  
  669. {
  670. ******************************************************************************
  671.  
  672.     BSContainerPIInit - Plug-in's initialization routine.  Called when 
  673.         plug-in is selected for a Container.  Plug-in's opportunity to 
  674.         initialize device, allocate data structures, etc.
  675.  
  676.     Inputs:        initContainer - a pointer to the Container this plug-in will 
  677.                 be attached to
  678.     Outputs:    info - information about the new Container
  679.                 backgroundTask - if true, the BackgroundTask entry point will
  680.                     be invoked in its own private task.
  681.     
  682.     Returns:    E_BSSuccess if successful
  683.     
  684.  *****************************************************************************
  685. }
  686.     BSContainerPIInit = ProcPtr;  { FUNCTION BSContainerPIInit(initContainer: BSContainerPtr; VAR info: BSContainerPIInfo; VAR backgroundTask: BOOLEAN): OSStatus; C; }
  687.  
  688. {
  689. ******************************************************************************
  690.  
  691.     BSContainerPICleanup - cleans up plug-in state
  692.  
  693.     Inputs:        container - the Container to clean up for
  694.  
  695.     Outputs:    <none>
  696.  
  697.     Returns:    E_BSSuccess if successful
  698.  
  699.  *****************************************************************************
  700. }
  701.     BSContainerPICleanup = ProcPtr;  { FUNCTION BSContainerPICleanup(container: BSContainerPtr): OSStatus; C; }
  702.  
  703. {
  704. ******************************************************************************
  705.  
  706.     BSContainerPIGoToState - Tells the Container to go the specified state
  707.  
  708.     Inputs:        container - the Container to take to the state
  709.                 accessState - the state to go to
  710.  
  711.     Outputs:    <none>
  712.  
  713.     Returns:    E_BSSuccess if successful
  714.  
  715.  *****************************************************************************
  716. }
  717.     BSContainerPIGoToState = ProcPtr;  { FUNCTION BSContainerPIGoToState(container: BSContainerPtr; accessState: UInt32): OSStatus; C; }
  718.  
  719. {
  720. ******************************************************************************
  721.  
  722.     BSContainerPIAddContainer - Informs the Container of a new sub-Container
  723.         being added
  724.  
  725.     Inputs:        destContainer - the Container we're adding to
  726.                 addedContainer - the Container being added
  727.  
  728.     Outputs:    <none>
  729.  
  730.     Returns:    E_BSSuccess if successful
  731.  
  732.  *****************************************************************************
  733. }
  734.     BSContainerPIAddContainer = ProcPtr;  { FUNCTION BSContainerPIAddContainer(destContainer: BSContainerPtr; addedContainer: BSContainerPtr): OSStatus; C; }
  735.  
  736. {
  737. ******************************************************************************
  738.  
  739.     BSContainerPIGetInfo - Gets information about a Container
  740.  
  741.     Inputs:        infoContainer - the Container to get information about
  742.  
  743.     Outputs:    info - the filled in information buffer
  744.  
  745.     Returns:    E_BSSuccess if successful
  746.  
  747.  *****************************************************************************
  748. }
  749.     BSContainerPIGetInfo = ProcPtr;  { FUNCTION BSContainerPIGetInfo(infoContainer: BSContainerPtr; VAR info: BSContainerPIInfo): OSStatus; C; }
  750.  
  751. {
  752. ******************************************************************************
  753.  
  754.     BSContainerPIBackgroundTask - an optional entry point that will be executed
  755.         within its own task context if the backgroundTask flag is set on exit
  756.         from the Container Plug-in's init routine
  757.     
  758.     Inputs:        container - the Container the Background Task is being invoked 
  759.                         on behalf of
  760.     
  761.     Outputs:    <none>
  762.     
  763.     Returns:    E_BSSuccessful if successful
  764.     
  765.  *****************************************************************************
  766. }
  767.     BSContainerPIBackgroundTask = ProcPtr;  { FUNCTION BSContainerPIBackgroundTask(container: BSContainerPtr): OSStatus; C; }
  768.  
  769.     BSContainerPolicyOpsPtr = ^BSContainerPolicyOps;
  770.     BSContainerPolicyOps = RECORD
  771.         header:                    BlockStoragePlugInInfo;
  772.         Examine:                BSContainerPIExamine;
  773.         Init:                    BSContainerPIInit;
  774.         Cleanup:                BSContainerPICleanup;
  775.         GoToState:                BSContainerPIGoToState;
  776.         AddContainer:            BSContainerPIAddContainer;
  777.         GetInfo:                BSContainerPIGetInfo;
  778.         BackgroundTask:            BSContainerPIBackgroundTask;
  779.     END;
  780.  
  781. {
  782. ******************************************************************************
  783.  
  784.     BSCPIBackgroundTask - a background task entry point for a Container plug-in.
  785.             BSCPIStartBackgroundTask may be used by the Container plug-in to
  786.             start one of these.  The task will be automatically terminated
  787.             after the Cleanup routine is executed
  788.     
  789.     Inputs:        theContainer - the Container this is running for
  790.                 theArg - the argument passed to BSMPIStartBackgroundTask
  791.                 
  792.     Outputs:    <none>
  793.     
  794.     Returns:    Errors are ignored but will be logged.
  795.  *****************************************************************************
  796. }
  797.     BSCPIBackgroundTask = ProcPtr;  { FUNCTION BSCPIBackgroundTask(theContainer: BSContainerPtr; theArg: UNIV Ptr): OSStatus; C; }
  798.  
  799. {
  800. ******************************************************************************
  801.  *******************************************************************************
  802.  *******************************************************************************
  803.  
  804.     Block Storage Family Services
  805.     
  806.  *******************************************************************************
  807.  *******************************************************************************
  808.  *****************************************************************************
  809. }
  810. {
  811. ******************************************************************************
  812.     BSStoreRW - Request I/O from another Store.  Used by Mapping Plug-ins.
  813.                 Not for use by Partitioning Plug-ins!!
  814.     
  815.     Inputs:        rwStore - the Store to do I/O with
  816.                 blocks - the blocks for the transfer
  817.                 memory - the memory for the transfer
  818.                 parentRequest - the BSIORequestPtr that the requestor was called
  819.                     with
  820.                 privateData - pointer to be given to the completion routine
  821.                     when it is called
  822.                 options - read/write
  823.                 
  824.     Outputs:    errors - where errors occurred, if any occurred
  825.     
  826.     Returns:    return code from other plug-in
  827.     
  828.  *****************************************************************************
  829. }
  830. FUNCTION BSStoreRW(rwStore: BSStorePtr; blocks: BSBlockListDescriptorRef; memory: MemListDescriptorRef; parentRequest: BSIORequestBlockPtr; privateData: UNIV Ptr; options: OptionBits; VAR errors: BSErrorListPtr): BSIOStatus; C;
  831. {
  832. ******************************************************************************
  833.     BSStoreFlush - Request another Store to flush its caches.  Used by Mapping Plug-ins.
  834.                 Not for use by Partitioning Plug-ins!!
  835.     
  836.     Inputs:        flushStore - the Store to flush
  837.                 parentRequest - the BSIORequestPtr that the requestor was called
  838.                     with
  839.                 privateData - pointer to be given to the completion routine
  840.                     when it is called
  841.                 
  842.     Outputs:    errors - where errors occurred, if any occurred
  843.     
  844.     Returns:    return code from other plug-in
  845.     
  846.  *****************************************************************************
  847. }
  848. FUNCTION BSStoreFlush(flushStore: BSStorePtr; parentRequest: BSIORequestBlockPtr; privateData: UNIV Ptr; VAR errors: BSErrorListPtr): BSIOStatus; C;
  849. {
  850. ******************************************************************************
  851.     BSTrackOtherFamilyRequest  - informs the Block Storage family code what routine 
  852.         should be called when the other I/O family the request is being passed to 
  853.         notifies the Block Storage family of its completion.  The Mapping plug-in's
  854.         ioCompletion routine will be called when the notification of the request
  855.         completion is received.
  856.  
  857.     Inputs:        ioStore - Store I/O is taking place in
  858.                 curRequest - BSIORequestBlock for which this I/O is taking place.
  859.                         This was the BSIORequestBlockPtr passed into the R/W 
  860.                         routine.
  861.                 privateData - Private data to be passed back when the completion routine
  862.                         is called.
  863.                 retNotify - Pointer to a kernel notification structure that will
  864.                         be filled in by BSTrackOtherFamilyRequest to be given
  865.                         to the other family in the async API call
  866.     
  867.     Outputs:    <none>
  868.     
  869.     Returns:    E_BSSuccess if able to track request
  870.  
  871.  *****************************************************************************
  872. }
  873. FUNCTION BSTrackOtherFamilyRequest(ioStore: BSStorePtr; curRequest: BSIORequestBlockPtr; privateData: UNIV Ptr; retNotify: KernelNotificationPtr): OSStatus; C;
  874. {
  875. ******************************************************************************
  876.     BSMPIStartBackgroundTask - starts a background task for a Mapping Plug-in.
  877.         The task will be terminated after the Cleanup routines for the Plug-in
  878.         is called for this Store.
  879.     
  880.     Inputs:        store - the Store the background task is being started for
  881.                 backgroundTask - the function to start
  882.                 arg - the argument to be passed to the function
  883.     
  884.     Outputs:    taskID - the task ID of the new task
  885.     
  886.     Returns:    E_BSSuccess if successful
  887.  
  888.  *****************************************************************************
  889. }
  890. FUNCTION BSMPIStartBackgroundTask(store: BSStorePtr; backgroundTask: BSMPIBackgroundTask; arg: UNIV Ptr; VAR taskID: TaskID): OSStatus; C;
  891. {
  892. ******************************************************************************
  893.     BSCPIStartBackgroundTask - starts a background task for a Container Plug-in.
  894.         The task will be terminated after the Cleanup routines for the Plug-in
  895.         is called for this Container.
  896.     
  897.     Inputs:        container - the Container the background task is being started for
  898.                 backgroundTask - the function to start
  899.                 arg - the argument to be passed to the function
  900.     
  901.     Outputs:    taskID - the task ID of the new task
  902.     
  903.     Returns:    E_BSSuccess if successful
  904.  
  905.  *****************************************************************************
  906. }
  907. FUNCTION BSCPIStartBackgroundTask(container: BSContainerPtr; backgroundTask: BSCPIBackgroundTask; arg: UNIV Ptr; VAR taskID: TaskID): OSStatus; C;
  908. {
  909. ******************************************************************************
  910.  *******************************************************************************
  911.  
  912.     Store Accessor functions
  913.     
  914.  *******************************************************************************
  915.  *****************************************************************************
  916. }
  917. {
  918. ******************************************************************************
  919.     BSGetMappingPIPrivateData - retrieves the Mapping Plug-in's private data
  920.         from a Store
  921.     
  922.     Inputs:        accessStore - the Store to retrieve the data from
  923.     
  924.     Outputs:    <none>
  925.     
  926.     Returns:    pointer to data
  927.  
  928.  *****************************************************************************
  929. }
  930. FUNCTION BSGetMappingPIPrivateData(accessStore: BSStorePtr): Ptr; C;
  931. {
  932. ******************************************************************************
  933.     BSSetMappingPIPrivateData - sets the Mapping Plug-in's private data
  934.         for a Store
  935.     
  936.     Inputs:        accessStore - the Store to set the data in
  937.                 privateData - pointer to the data
  938.     
  939.     Outputs:    <none>
  940.     
  941.     Returns:    <none>
  942.  
  943.  *****************************************************************************
  944. }
  945. PROCEDURE BSSetMappingPIPrivateData(accessStore: BSStorePtr; privateData: UNIV Ptr); C;
  946. {
  947. ******************************************************************************
  948.     BSGetPartitioningPIPrivateData - retrieves the Partitioning Plug-in's private 
  949.         data from a Store
  950.     
  951.     Inputs:        accessStore - the Store to retrieve the data from
  952.     
  953.     Outputs:    <none>
  954.     
  955.     Returns:    pointer to data
  956.  
  957.  *****************************************************************************
  958. }
  959. FUNCTION BSGetPartitioningPIPrivateData(accessStore: BSStorePtr): Ptr; C;
  960. {
  961. ******************************************************************************
  962.     BSSetPartitioningPIPrivateData - sets the Partitioning Plug-in's private data
  963.         for a Store
  964.     
  965.     Inputs:        accessStore - the Store to set the data in
  966.                 privateData - pointer to the data
  967.     
  968.     Outputs:    <none>
  969.     
  970.     Returns:    <none>
  971.  
  972.  *****************************************************************************
  973. }
  974. PROCEDURE BSSetPartitioningPIPrivateData(accessStore: BSStorePtr; privateData: UNIV Ptr); C;
  975. {
  976. ******************************************************************************
  977.     BSStoreGetNumComponents - Gets the number of component Stores or Devices 
  978.         that have been put together into this Store
  979.     
  980.     Inputs:        accessStore - the Store to get the number of components from
  981.     
  982.     Outputs:    <none>
  983.     
  984.     Returns:    number of components
  985.  
  986.  *****************************************************************************
  987. }
  988. FUNCTION BSStoreGetNumComponents(accessStore: BSStorePtr): ItemCount; C;
  989. {
  990. ******************************************************************************
  991.     BSStoreGetComponents - Gets the information about a particular component
  992.         of a Store
  993.     
  994.     Inputs:        accessStore - the Store to get the number of components from
  995.                 componentNum - which component to return
  996.     
  997.     Outputs:    component - the BSStoreComponent buffer that is filled in
  998.     
  999.     Returns:    E_BSSuccess if no problems
  1000.  
  1001.  *****************************************************************************
  1002. }
  1003. FUNCTION BSStoreGetComponent(accessStore: BSStorePtr; componentNum: ItemCount; component: BSStoreMPIComponentPtr): OSStatus; C;
  1004. {
  1005. ******************************************************************************
  1006.     BSStoreSetNumPartitions - sets the number of partitions in the Store
  1007.     
  1008.     Inputs:        accessStore - the Store to get the number of components from
  1009.                 numPartitions - the new partition count
  1010.     
  1011.     Outputs:    <none>
  1012.     
  1013.     Returns:    <none>
  1014.  
  1015.  *****************************************************************************
  1016. }
  1017. PROCEDURE BSStoreSetNumPartitions(accessStore: BSStorePtr; numPartitions: ItemCount); C;
  1018. {
  1019. ******************************************************************************
  1020.     BSStoreGetPPIConnection - Gets the Store connection for the partitioning 
  1021.         plug-ins
  1022.     
  1023.     Inputs:        accessStore - the Store to get connection from
  1024.     
  1025.     Outputs:    <none>
  1026.     
  1027.     Returns:    Connection to the Store (kInvalidID if none)
  1028.  
  1029.  *****************************************************************************
  1030. }
  1031. FUNCTION BSStoreGetPPIConnection(accessStore: BSStorePtr): BSStoreConnID; C;
  1032. {
  1033. ******************************************************************************
  1034.     BSStoreGetAccessibilityState - Gets the current accessibility state of the Store
  1035.     
  1036.     Inputs:        accessStore - the Store to get connection from
  1037.     
  1038.     Outputs:    <none>
  1039.     
  1040.     Returns:    Store's state
  1041.  
  1042.  *****************************************************************************
  1043. }
  1044. FUNCTION BSStoreGetAccessibilityState(accessStore: BSStorePtr): BSAccessibilityState; C;
  1045. {
  1046. ******************************************************************************
  1047.     BSStoreSetAccessibilityState - Sets the current accessibility state of the Store
  1048.     
  1049.     Inputs:        accessStore - the Store to get connection from
  1050.                 setState - the state to set the Store to
  1051.     
  1052.     Outputs:    <none>
  1053.     
  1054.     Returns:    <none>
  1055.  
  1056.  *****************************************************************************
  1057. }
  1058. PROCEDURE BSStoreSetAccessibilityState(accessStore: BSStorePtr; setState: BSAccessibilityState); C;
  1059. {
  1060. ******************************************************************************
  1061.     BSStoreGetMPIInfo - Calls the GetInfo routine of the Mapping plug-in 
  1062.         attached to the Store
  1063.     
  1064.     Inputs:        accessStore - the Store to get connection from
  1065.                 info - a pointer to the buffer to put the returned info into
  1066.     
  1067.     Outputs:    <none>
  1068.     
  1069.     Returns:    <none>
  1070.  
  1071.  *****************************************************************************
  1072. }
  1073. FUNCTION BSStoreGetMPIInfo(accessStore: BSStorePtr; VAR info: BSStoreMPIInfo): OSStatus; C;
  1074. {
  1075. ******************************************************************************
  1076.     BSStoreGetPPIInfo - Calls the GetInfo routine of the Partitioning plug-in 
  1077.         attached to the Store
  1078.     
  1079.     Inputs:        accessStore - the Store to get connection from
  1080.                 info - a pointer to the buffer to put the returned info into
  1081.     
  1082.     Outputs:    <none>
  1083.     
  1084.     Returns:    <none>
  1085.  
  1086.  *****************************************************************************
  1087. }
  1088. FUNCTION BSStoreGetPPIInfo(accessStore: BSStorePtr; VAR info: BSStorePPIInfo): OSStatus; C;
  1089. {
  1090. ******************************************************************************
  1091.  
  1092.     BSMPINotifyFamilyStoreChangedState - called from a Mapping Plug-in (typically
  1093.         in the BackgroundTask) to inform the Block Storage Family of an 
  1094.         unexpected accessibility change, e.g. the media was removed or the disk
  1095.         spun down.
  1096.  
  1097.     Inputs:        changedStore - the Store that changed
  1098.                 newState - the state the Store is now in
  1099.                 
  1100.     Outputs:    <none>
  1101.  
  1102.     Returns:    E_BSSuccess if successful
  1103.  
  1104.  *****************************************************************************
  1105. }
  1106. FUNCTION BSMPINotifyFamilyStoreChangedState(changedStore: BSStorePtr; newState: BSAccessibilityState): OSStatus; C;
  1107. {
  1108. ******************************************************************************
  1109.  
  1110.     BSMPIRequestStoreStateChange - requests a state change of the Store.  This
  1111.         should be used, for example, if a device has an eject button that can
  1112.         be monitored by the Mapping Plug-in.  If the eject button is pressed
  1113.         BSMPIRequestStoreStateChange should be used to notify the Family that
  1114.         an eject has been requested and the Family can then notify clients and
  1115.         flush data to the media properly.  This call waits until permission is
  1116.         granted or denied by the Expert.  The GoToState call of the plug-in
  1117.         will be invoked before this calls returns if permission is granted.
  1118.  
  1119.     Inputs:        changeStore - the Store the state change will affect
  1120.                 requestedState - the state the Store is being requested to go to
  1121.  
  1122.     Outputs:    permission - true if permission was granted and the Store 
  1123.                     successfully went to the State requested.
  1124.  
  1125.     Returns:    E_BSSuccess if successful
  1126.  
  1127.  *****************************************************************************
  1128. }
  1129. FUNCTION BSMPIRequestStoreStateChange(changeStore: BSStorePtr; requestedState: BSAccessibilityState; VAR permission: BOOLEAN): OSStatus; C;
  1130. {
  1131. ******************************************************************************
  1132.  
  1133.     BSCPINotifyFamilyContainerChangedState - called from a Container Plug-in 
  1134.         (typically in the BackgroundTask) to inform the Block Storage Family of 
  1135.         an unexpected accessibility change, e.g. the media was removed.
  1136.  
  1137.     Inputs:        changedStore - the Store that changed
  1138.                 newState - the state the Store is now in
  1139.                 
  1140.     Outputs:    <none>
  1141.  
  1142.     Returns:    E_BSSuccess if successful
  1143.  
  1144.  *****************************************************************************
  1145. }
  1146. FUNCTION BSCPINotifyFamilyContainerChangedState(changedContainer: BSContainerPtr; newState: BSAccessibilityState): OSStatus; C;
  1147. {
  1148. ******************************************************************************
  1149.  
  1150.     BSCPIRequestContainerStateChange - requests a state change of the Container. 
  1151.         This should be used, for example, if a device has an eject button that 
  1152.         can be monitored by the Container Plug-in.  If the eject button is pressed
  1153.         BSCPIRequestStoreStateChange should be used to notify the Family that
  1154.         an eject has been requested and the Family can then notify clients and
  1155.         flush data to the media properly.  This call waits until permission is
  1156.         granted or denied by the Expert.  The GoToState call of the plug-in
  1157.         will be invoked before this calls returns if permission is granted.
  1158.  
  1159.     Inputs:        changeContainer - the Container the state change will affect
  1160.                 requestedState - the state the Container is being requested to go to
  1161.  
  1162.     Outputs:    permission - true if permission was granted and the Container 
  1163.                     successfully went to the State requested.
  1164.  
  1165.     Returns:    E_BSSuccess if successful
  1166.  
  1167.  *****************************************************************************
  1168. }
  1169. FUNCTION BSCPIRequestContainerStateChange(changeContainer: BSStorePtr; requestedState: BSAccessibilityState; VAR permission: BOOLEAN): OSStatus; C;
  1170. {$ENDC}
  1171. {$ALIGN RESET}
  1172. {$POP}
  1173.  
  1174. {$SETC UsingIncludes := BlockStoragePluginIncludes}
  1175.  
  1176. {$ENDC} {__BLOCKSTORAGEPLUGIN__}
  1177.  
  1178. {$IFC NOT UsingIncludes}
  1179.  END.
  1180. {$ENDC}
  1181.